home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 033a / cwexp104.zip / EXPIRE.DOC < prev    next >
Text File  |  1991-10-22  |  12KB  |  269 lines
  1.    EXPIRE Version 1.03 - A DOS Waffle utility to provide news expiration
  2.    based on age of articles. Optionally, expire will also expire files in
  3.    user-specified directories.
  4.  
  5.    This expire program is freeware; you may use it, modify it, or
  6.    distribute it freely.  Though not required, it would be nice if you'd
  7.    give at least a little acknowledgement to the original author in any
  8.    modified version(s) you create.
  9.  
  10.  
  11.    DISTRIBUTION FILE:
  12.       CWEXP102.ZIP, containing expire.c, getopt.c, expire.com, and expire.doc
  13.    
  14.    AUTHOR: Chris Winemiller, cwinemil@keys.lonestar.org
  15.  
  16.    HISTORY:
  17.       02 April 1991  1.0   Chris Winemiller. Original version.
  18.       09 July 1991   1.01  Chris Winemiller. Corrected the "usage"
  19.                            info printed out when one enters "expire -h".
  20.                            Previously, the usage explained the -t option
  21.                            but failed to place it in the invocation info.
  22.                            (I.e., previously said "expire [-a -n]" rather
  23.                            than "expire [-a -n -t -h]".) Oh--I also added
  24.                            the -h option to this list.  Actually, any
  25.                            option other than -a, -n, or -t will cause
  26.                            the usage to print out. Expanded the help output
  27.                            to mention the /mexp attribute.
  28.        20 Sep 1991 1.02    Chris Winemiller. Added "-e <expire_file>"
  29.                            option to name an "expire" file. This file will
  30.                            contain the name of directories whose files
  31.                            should be subjected to expiration.  Thanks to
  32.                            Bob Kirkpatrick (bobk@dogear.spk.wa.us) for
  33.                            suggesting the existence and format of this file.
  34.        21 Oct 1991 1.03    Modified so that expire prints out the total
  35.                            number of files and total number of bytes deleted.
  36.                            These statistics are printed just before expire
  37.                            terminates.
  38.        22 Oct 1991 1.04    Added a couple more statistics printed out at the
  39.                            end: files per second and bytes per second that
  40.                            were deleted (and total time, too).
  41.       
  42.    INVOCATION:
  43.  
  44.       expire [-a -e <expire_file> -n -t -h]
  45.         (NOTE: specify multiple options separately!)
  46.         where:
  47.                -a = Consider all files in each news group directory or for
  48.                     expire directory for possible deletion. (Default:
  49.                     consider only files whose names are composed of only
  50.                     numerical characters (0-9) and no filename extension.)
  51.  
  52.                -e = Name of an "expire" file. This file contains the names
  53.                     of directories whose files should be subjected to
  54.                     expiration.  (Multiple -e options are permitted.)
  55.  
  56.                -h = Help.  Produces the "usage" printout.
  57.  
  58.                -n = No file deletions are performed, but otherwise
  59.                     produces the same output. (I.e., -n will report the
  60.                     files that should be deleted, but doesn't delete
  61.                     them.)
  62.  
  63.                -t = Display the expiration time for each news group.
  64.  
  65.                Any other attempted option produces a usage ("-h") description.
  66.  
  67.    COMPILATION COMMAND (if compiling the source, using Turbo C compiler): 
  68.  
  69.       tcc -mt -lt expire.c getopt.c
  70.                         where -mt specifies tiny model for compilation and
  71.                         -lt tells the linker to produce a .COM executable.
  72.  
  73.  
  74.    OPTIONS THAT EXPIRE LOOKS FOR IN WAFFLE'S FORUM FILES
  75.  
  76.    Expire looks for the /mexp=hh attribute in Waffle forum files, where hh
  77.    is the number of hours files will be retained. The default is 72 hours.
  78.    (That is, 72 hours will be used if no /mexp=hh attribute appears in a
  79.    forum file.) If /mexp=hh appears on a DEFAULT or FORUM line, it applies
  80.    to all following newsgroups in the forum file until changed on a later
  81.    DEFAULT or FORUM line. However, /mexp=hh on a newsgroup line applies
  82.    only to that one newsgroup, overriding the current default value. 
  83.  
  84.    The /dir=<directory_name> attribute is an attribute of a Waffle forum
  85.    file that is also recognized by the expire program. It is interpreted by
  86.    the expire program exactly the same way as it is interpreted by Waffle.
  87.    When /dir=<directory_name> appears on a DEFAULT or FORUM line,
  88.    <directory_name> is the name of the root directory for news. (For
  89.    example, /dir=c:/news means that all news appears under the c:/news
  90.    directory.) When /dir=<directory_name> appears on a news group line,
  91.    <directory_name> is the full pathname of the directory containing
  92.    articles for that one news group. (For example, if
  93.    /dir=c:/news/comp/os/msdos/programr appears on the line for the
  94.    newsgroup named comp.os.msdos.programmer, it names the directory
  95.    containing articles for that news group.)
  96.  
  97.    (Note: The forum file names are extracted from Waffle's static file,
  98.    whose pathname is given by the WAFFLE environment variable.)
  99.  
  100.    Now for an example: let's say Waffle has a forum file named USENET,
  101.    which names all the Usenet newsgroups it receives. It may look like
  102.    this:
  103.  
  104.    # ------------------------- START OF USENET FILE ------------------------
  105.  
  106.    # This file names the location and characteristics of various Usenet
  107.    # newsgroups that are carried here.
  108.    #
  109.    # Use /dir to specify the root of the directory tree containing
  110.    # the news. (Useful only for DOS Waffle systems.)
  111.    #
  112.    # Waffle's /keep attribute isn't used. Instead, use the /mexp
  113.    # attribute to cause news to expire according to its age.
  114.  
  115.  
  116.    DEFAULT /sig=sig /dir=C:/news /name="[Newsgroup %N]" /spy=monitor
  117.  
  118.    # Set default expiration to 4 days (/mexp=96 hours).  Other values are
  119.    # set as desired.
  120.  
  121.    DEFAULT /type=USENET /new=1 /mexp=96
  122.    DEFAULT /warn=C:/waffle/system/warning /fast=1
  123.    DEFAULT /ask=Distribution,Keywords /dist=world /post=3 /read=0
  124.  
  125.    alt.bbs.waffle
  126.  
  127.    # Note: The Expire program will read the /dir directive; it knows
  128.    # that the alt.msdos.programmer newsgroup is in the directory named
  129.    # C:/news/alt/msdos/programr.
  130.  
  131.    alt.msdos.programmer       /dir=C:/news/alt/msdos/programr
  132.  
  133.    # IBM binaries are important, so let's keep them around for 7 days
  134.    # (168 hours) in comp.binaries.ibm.pc
  135.  
  136.    comp.binaries.ibm.pc       /mod /mexp=168
  137.  
  138.    # The comp.binaries.ibm.pc.d newsgroup is expired at the most recent
  139.    # default value (96 hours, or 4 days).
  140.  
  141.    comp.binaries.ibm.pc.d
  142.  
  143.    # Set default expirations for the following control groups.  Entries
  144.    # will be kept for about a month.
  145.  
  146.    DEFAULT /mexp=720
  147.  
  148.    # Things that we are fed but do not carry get shoved into "junk".
  149.    # If things get placed in junk often, something is wrong.  Let's
  150.    # expire its articles after 2 days (48 hours).
  151.  
  152.    junk            /post=9 /mexp=48
  153.  
  154.    # /spy without arguments sets the "monitor" group as a destination
  155.    # for copies of any posts originating locally..  (expired after 720
  156.    # hours, which is the most recent default value).
  157.  
  158.    monitor            /post=0 /spy
  159.  
  160.    # You *MUST* have a "control" group. Right now we don't do a whole
  161.    # lot of control messages processing in the DOS version, though.
  162.    # (Also expired after 720 hours.)
  163.  
  164.    control            /post=0
  165.  
  166.    # ------------------------- END OF USENET FILE ------------------------
  167.  
  168.  
  169.  
  170.    OPTIONS THAT EXPIRE LOOKS FOR IN AN EXPIRE FILE
  171.  
  172.    An expire file contains a list of directories plus optional DEFAULT
  173.    lines and optional attributes. (The format of an expire file is
  174.    discussed below.) Files in those directories will be subjected to
  175.    expiration. An expire file is named by the "-e <expire_file>" option on
  176.    the command line when invoking the expire program. (Multiple "-e"
  177.    options are permitted.) If expire is invoked with no "-e" options, no
  178.    expire files are read. Expire files are considered AFTER forum files are
  179.    considered. Important Note: If you use the expire file (via the "-e"
  180.    option), you probably also want to use the "-a" option which causes all
  181.    files to be considered. Otherwise, only files with numerical file names
  182.    (like news article names!) will be considered. If this conflicts with
  183.    how you want to treat real newsgroup directories, you will simply have
  184.    to invoke expire twice: once without the -a and -e options, and once
  185.    with them.
  186.  
  187.    The /mexp=hh attribute is recognized in an expire file. It has the exact
  188.    same meaning as it does in a Waffle forum file: it names the number of
  189.    hours that files will be retained. (The default is 72 hours.) If
  190.    /mexp=hh appears on a DEFAULT line, it applies to all following
  191.    directories in the expire file until changed on a later DEFAULT line.
  192.    However, if /mexp=hh appears on a line naming a directory, it applies
  193.    only to that one directory, overriding the current default expiration
  194.    time.
  195.  
  196.    The /exclude=<file_names> attribute is also recognized in an expire
  197.    file. (It is NOT recognized in a Waffle forum file.) It names files to
  198.    be excluded from expire's consideration. The default is: No files are
  199.    excluded (i.e., All files are subject to expiration). If
  200.    /exclude=<file_names> appears on a DEFAULT line, it applies to all
  201.    following directories in the expire file until changed on a later
  202.    DEFAULT line. If /exclude=<file_names> appear on a line naming a
  203.    directory, it applies only to that directory and overrides the current
  204.    default /exclude.
  205.  
  206.    The format of <file_names> for the /exclude option is a comma-separated
  207.    list of file names (no embedded spaces!).  For example:
  208.  
  209.         /exclude=sample.txt,newfile,mail.1,mail.2
  210.  
  211.    NOTE: No wild card characters are recognized!
  212.  
  213.    One other thing: the expression "/exclude=" (with no file names!)
  214.    means that NO files are excluded, until changed by some later
  215.    /exclude attribute. This is a handy way to get make all files
  216.    subject to expiration, after previously naming some set of files to
  217.    remain untouched. (See the example expire file below.)
  218.  
  219.  
  220.    THE FORMAT OF AN EXPIRE FILE
  221.  
  222.    The format of an expire file is very simple.  Each line is either:
  223.    1. A blank line, which is ignored.
  224.    2. A comment line (one which has a '#' character in column 1); this
  225.       line is also ignored.
  226.    3. A DEFAULT line (one whose first word is DEFAULT (upper or lower
  227.       case), with /exclude or /mexp attributes after the word DEFAULT).
  228.    4. A directory line (one which contains the full pathname of one directory,
  229.       optionally followed by /exclude or /mexp attributes).
  230.  
  231.    Now for an example: let's say we have an expire file named EXPDIRS,
  232.    which names all the directories whose files we want to expire. It may
  233.    look like this (NOTE: The '#' characters MUST be in COLUMN 1 of your file!):
  234.  
  235.    # ------------------------- START OF EXPDIRS FILE ------------------------
  236.    #<--- This '#' character must be in column 1 of the file!
  237.    #
  238.    # This is an expire file.  It names directories which the expire
  239.    # program will consider for expiration AFTER all Waffle news groups have
  240.    # been considered.
  241.  
  242.    # Let's set some defaults.  Unless otherwise specified, let's retain
  243.    # files for 168 hours (1 week), and NEVER get rid of files named
  244.    # "readme.txt" or "notouch.me".  (Note: file names are NOT case sensitive.)
  245.  
  246.    DEFAULT /mexp=168 /exclude=readme.txt,notouch.me
  247.  
  248.    c:/misc
  249.  
  250.    # Waffle's outbox and /user/uucp directories fill up quickly, so
  251.    # let's expire their files after 24 hours.  Also, we want to get rid
  252.    # of all files, but don't change the current defaults for /exclude.
  253.  
  254.    DEFAULT /mexp=24
  255.    c:/spool/outbox /exclude=
  256.    c:/user/uucp /exclude=
  257.  
  258.    # Allow users to retain their files for 2 weeks (336 hrs), and then let's
  259.    # delete them.  But never get rid of files like the signature files and
  260.    # a few others.
  261.  
  262.    DEFAULT /mexp=336 /exclude=join,sig,mailsig,postsig,waffle
  263.    d:/user/jackb
  264.    d:/user/donh
  265.    d:/user/billb
  266.    d:/user/root
  267.  
  268.    # ------------------------- END OF EXPDIRS FILE ------------------------
  269.